Creating
a Query
To create a
new query, call the PdhOpenQuery function. The function returns a handle to the query to
be used in other PDH function calls. You can create multiple queries to be used
in your program.
After you
create a query, call the PdhAddCounter function to add a counter to the query. Call PdhAddCounter
for each counter to be added to the query. You can use one of the following
methods to determine which counters to use.
Hard-code the counter name in
the call to PdhAddCounter. Use this method if you always monitor the
same counter.
Read the name from the registry
or an initialization file. Use this method if the set of counters you monitor
can change.
Call the PdhBrowseCounters function to display the PDH
browse dialog box. The dialog box allows the user to browse and select
performance counters. The function returns one or more counter path strings for
use in a query. If you add the counter returned by PdhBrowseCounters to
a query, you can use the PdhRemoveCounter function to remove the counter from the query.
Counter Paths
The counter
names used by PDH are expressed as counter paths. A counter path uses a
collection of hierarchical elements to describe a counter. In the same way that
a file path includes drives, directories, subdirectories, and file names, a
counter path includes machines, objects, instances, and counter names. The
syntax for a counter path is:
\\Machine\PerfObject(ParentInstance/ObjectInstance#InstanceIndex)\Counter
The \\Machine
component is optional; it specifies the name of the machine. If you do not
supply this component, PDH uses the local machine name. Therefore, a single
path string works on any machine that supports the counter.
The
\PerfObject component is required; it specifies the performance object that
contains the performance counter. These objects are listed in the PDH browse
dialog box and in Performance Monitor Add To Chart dialog box, in the Objects
combo box. If this object has a variable list of instances, then you must also
specify an instance string.
The
(ParentInstance/ObjectInstance#InstanceIndex) component is only required if the
object supports multiple instances. If the instance supports a variable list of
instances, then you must specify an instance string. The format of the string
depends on the object type. If the object has simple instances, then the format
is just the instance name enclosed in parentheses. For example:
(Explorer)
If the
instance of this object requires a parent instance name as well, then the
parent instance name must come before the object instance, and be separated by
a forward slash character. For example:
(Explorer/0)
If the object
has multiple instances that have the same name string, they can be indexed
sequentially by specifying the instance index prefixed by a pound sign.
Instance indexes are 0-based, so all instances have an implicit 0 index. For
example:
(Explorer/0#1)
The \Counter
component is required; it specifies the performance counter. The counter names
are displayed in the PDH browse dialog box and in the Performance Monitor Add
To Chart dialog box, in the Counters list box. The counters
associated with the selected object are displayed.
The following
are two common counters in the PDH counter path format:
\Processor(0)\% Processor Time
\System\% Total Processor Time